ADF Data Description API v1.5.3 RF

The Allotrope Data Format (ADF) [[!ADF]] consists of several APIs and taxonomies. This document constitutes the specification for the ADF Data Description (ADF-DD). It defines how to store meta data of Data Package and Data Cubes along with experimental or process data and contextual meta data. ADF-DD is based on semantic web and linked data concepts using the RDF Data Model.

Disclaimer

THESE MATERIALS ARE PROVIDED "AS IS" AND ALLOTROPE EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF NON-INFRINGEMENT, TITLE, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Introduction

The Allotrope Data Format (ADF) defines an interface for storing scientific observations from analytical chemistry. It is intended for long-term stability of archived analytical data and fast real-time access to it. The ADF Data Description (ADF-DD) API defines an interface for storing functional and technical meta data.

The document is structured as follows: Next, the role of the ADF Data Description within the high-level structure of ADF is shown. Then, the requirements are listed, the core graph operations (query, insert, delete) are described.

Examples of the different operations are given in the Developer's Guide [[ADF-DD-DG]].

Document Conventions

Namespaces

Within this specification, the following namespace prefix bindings are used:

Prefix	Namespace
owl:	http://www.w3.org/2002/07/owl#
rdf:	http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs:	http://www.w3.org/2000/01/rdf-schema#
xsd:	http://www.w3.org/2001/XMLSchema#
skos:	http://www.w3.org/2004/02/skos/core#
dct:	http://purl.org/dc/terms/
foaf:	http://xmlns.com/foaf/0.1/

Indication of Requirement Levels

Within this document the definitions of MUST, SHOULD and MAY are used as defined in [[!rfc2119]].

Number Formatting

Within this document, decimal numbers will use a dot "." as the decimal mark.

RDF Graph Operations

The Data Description API MUST provide functions for the core operations on the RDF graph - i.e. the data stored in the ADF triple store (ADF-QS) [[ADF-QS]].

The API of Apache Jena [[APACHE-JENA]] constitutes the ADF Data Description API. In the following sections, the core functions of the API are described, examples are given in the ADF Data Description API Developer's Guide [[ADF-DD-DG]]. For a complete description of the API, please consult the JavaDoc API documentation and the sources listed in the References section.

The RDF Graph

In Apache Jena, an RDF graph [[!RDF]] is called a model and is represented by the Model interface [[APACHE-JENA]], [[JENA-INTRO]]. Basically, the Jena Model that represents the RDF graph consists of a set of statements (also called triples), where each statement consists of a subject, predicate and object. The following sections describe the basic operations on the RDF graph. For more details on the Jena API, it is referred to [[APACHE-JENA]] and [[JENA-INTRO]].

Querying an RDF Graph

The RDF graph MAY be queried by iterating over its statements or by executing SPARQL [[!SPARQL]] queries on it.

Modifying an RDF Graph

The ADF-DD API MUST provide methods to modify the RDF Graph. 'Modify' means adding, removing and updating statements. Modification MUST be possible via the API and via SPARQL 1.1 UPDATE queries.

Inserting Statements into an RDF Graph

Statements MAY be created and inserted into the RDF graph either via the API method or via a SPARQL query using the INSERT operation. Note that in an RDF graph a statement is uniquely identified by its subject, predicate and object. Thus, if a statement already exists, no new statement MAY be created.

Removing a Statement from the RDF Graph

To remove statements from an RDF graph, the API method for removal MAY be used or a SPARQL query using the DELETE operation. For the latter, the removal with a SPARQL update query MAY optionally be based on a condition specified in a WHERE clause.

Updating a Statement in the RDF Graph

Updating statements in an RDF graph MAY be realized by combining INSERT and DELETE operations in one SPARQL Update query.

Change History

Version	Release Date	Remarks
0.3.0	2015-04-30	Initial Working Draft version
0.4.0	2015-06-29	Included disclaimer information Harmonized layout across ADF specifications Harmonized structure across ADF specifications Moved all examples to the ADF-DD API Developer's Guide
1.0.0	2015-09-17 RC	Added Indication of Requirement Levels section Enforced usage of specification specific keywords Replaced ADF-DD API User's Guide by ADF-DD API Developer's Guide Clarified the operations in section RDF Graph Operations
1.0.0	2015-09-29	Updates versions, dates and document status Added captions to figures
1.1.0 RC	2016-03-11	Updated versions, dates and document status Added section on number formatting to document conventions Updated Fig. 1
1.1.0 RF	2016-03-31	Updated versions, dates and document status
1.1.5	2016-05-13	Updated versions and dates
1.2.0 Preview	2016-09-23	Updated versions and dates
1.2.0 RC	2016-12-07	Updated versions and dates Changed reference from ADF-TS to ADF-QS
1.3.0 Preview	2017-03-31	Updated versions and dates
1.3.0 RF	2017-06-30	Updated versions and dates Updated images
1.4.5 RF	2018-12-17	Updated versions and dates
1.5.0 RC	2019-12-12	Updated versions and dates
1.5.0 RF	2020-03-03	Updated HDF5 reference link Added overwritten images
1.5.3 RF	2020-11-30	Updated broken reference links Updated PURL and DOCS server links to relative links Reformat the document header

Allotrope Data Description API v1.5.3 RF